Component Variants in Figma are different versions of similar components grouped together inside a single component set. They are useful when a component needs predictable variations such as different states, sizes, types, colors, themes, or layouts. Instead of maintaining many separate components, designers can organize related versions into one structured system and allow users to switch between them through variant properties.
For professional Figma design-system training, explore JustAcademy Figma Training and Register for Figma Course Demo.
A Component Variant is a specific version of a component that differs from other versions in predictable ways. Multiple related components can be combined into a component set, where variant properties define the differences between them.
For example, a button may have Primary, Secondary, Small, Large, Hover, Pressed, and Disabled versions. These can be organized as variants instead of being maintained as completely separate components.
Component Variants are related versions of a reusable component organized inside one component set.
Button Component Set
├── Primary
├── Secondary
├── Disabled
├── Hover
└── Pressed
Large design systems can contain hundreds or thousands of components. Without a proper variant system, similar components can become difficult to find and maintain. Variants group related components into an organized structure and make them easier to use.
Component Set
│
├── Variant 1
│ ├── Type = Primary
│ ├── Size = Small
│ └── State = Default
│
├── Variant 2
│ ├── Type = Primary
│ ├── Size = Medium
│ └── State = Hover
│
├── Variant 3
│ ├── Type = Secondary
│ ├── Size = Large
│ └── State = Default
│
└── Variant 4
├── Type = Destructive
├── Size = Medium
└── State = Disabled
A component set is a container that groups related component variants. When components are combined as variants, Figma places them inside a component set. The component set is displayed on the canvas with a dashed purple boundary by default.
A component set helps designers treat many related component versions as one organized component family.
| Component | Component Variant |
|---|---|
| Reusable design object | Specific version of a reusable component |
| Can exist independently | Usually belongs to a component set |
| Represents a reusable UI element | Represents a predictable variation |
| Example: Button | Example: Button / Primary / Large |
A variant property defines an attribute by which variants differ. Common variant properties include Type, Size, State, Color, Theme, Density, and Orientation.
Property: Size
Values:
Small
Medium
Large
A variant value is a specific option belonging to a variant property.
Property: State
Values:
Default
Hover
Pressed
Disabled
Here, State is the property and Default, Hover, Pressed, and Disabled are its values.
| Property | Possible Values |
|---|---|
| Type | Primary, Secondary, Tertiary |
| Size | Small, Medium, Large |
| State | Default, Hover, Pressed, Disabled |
| Theme | Light, Dark |
| Density | Compact, Comfortable |
Use variants when multiple versions of a component serve the same general purpose and differ in predictable ways.
Not every customization should become a variant. If the difference can be handled more effectively with another component property or layout feature, use that approach instead.
| Component | Possible Variants |
|---|---|
| Button | Primary, Secondary, Disabled, Hover |
| Input | Default, Focus, Error, Success, Disabled |
| Checkbox | Unchecked, Checked, Indeterminate, Disabled |
| Navigation Item | Default, Hover, Active, Disabled |
| Badge | Success, Warning, Error, Information |
| Card | Default, Featured, Compact, Large |
Before creating variants, you can create the individual components that represent the required variations.
You can create a new variant from an existing component or component set.
Once a component set exists, you can continue adding variants to it. You can create additional variants, duplicate an existing variant, or add other related components to the component set.
Existing Component Set
↓
Add Variant
↓
Duplicate Variant
↓
Modify Design
↓
Assign Property Values
↓
New Variant
A professional button component set may use three major variant properties.
Button
Type:
Primary
Secondary
Destructive
Size:
Small
Medium
Large
State:
Default
Hover
Pressed
Disabled
| Type | Size | State |
|---|---|---|
| Primary | Small | Default |
| Primary | Medium | Hover |
| Primary | Large | Pressed |
| Secondary | Medium | Default |
| Destructive | Large | Disabled |
Good naming is essential for a scalable design system. Property names should clearly communicate the dimension of variation.
Good example:
Type = Primary
Size = Large
State = Hover
Poor example:
Property 1 = A
Property 2 = B
Property 3 = C
Figma supports slash-based naming to organize components and help convert existing components into variants.
Button/Primary/Large/Default
Button/Secondary/Medium/Hover
Button/Destructive/Small/Disabled
The first part can become the component set name, while the following parts can become variant property values when the components are combined as variants.
Button/Primary/Large/DefaultThis can be interpreted as:
When converting existing components into variants using slash naming, keep the naming structure consistent. The components being combined should use the same number of slash-separated levels so that the generated properties and values remain consistent.
Figma may initially create generic property names such as Variant, Property 2, and Property 3 when converting components. These should be renamed to meaningful names.
Buttons frequently require multiple interaction states.
Button
├── Default
├── Hover
├── Pressed
├── Focus
└── Disabled
The State property can be used to organize these predictable states.
Variants can represent predefined component sizes.
Size
├── Small
├── Medium
└── Large
Each size can have appropriate typography, padding, height, icon spacing, and other design characteristics.
Buttons and other controls may have different semantic or visual types.
Type
├── Primary
├── Secondary
├── Tertiary
└── Destructive
Variants can represent meaningful theme differences when distinct component versions are required.
Theme
├── Light
└── Dark
For broader design-token management, variables can also be used alongside components and variants.
Navigation Item
├── Default
├── Hover
├── Active
├── Selected
└── Disabled
| Variant | Purpose |
|---|---|
| Default | Normal input state |
| Focus | Input is currently selected |
| Filled | Input contains content |
| Error | Input contains invalid data |
| Success | Input contains valid data |
| Disabled | Input cannot be edited |
Card
├── Standard
├── Featured
├── Compact
├── Horizontal
└── Disabled
Badge
├── Success
├── Warning
├── Error
├── Information
└── Neutral
Checkbox
├── Unchecked
├── Checked
├── Indeterminate
├── Disabled
└── Error
Radio
├── Unselected
├── Selected
├── Disabled
└── Error
Toggle
├── Off
├── On
├── Off Disabled
└── On Disabled
For a scalable design system, consider separating concepts such as state and disabled status into separate properties when that produces a clearer and more reusable architecture.
Tab
├── Active
├── Inactive
├── Hover
└── Disabled
Menu Item
├── Default
├── Hover
├── Selected
├── Active
└── Disabled
A component-set instance allows designers to select different variant values without manually recreating the component. When an instance of a component set is placed on the canvas, its properties can be configured from the right sidebar.
Component Set
↓
Create Instance
↓
Select Instance
↓
Configure Properties
↓
Choose Variant
↓
Updated Instance
Figma uses the variant in the top-left position of a component set as the default variant. This variant represents the component set in the Assets panel and is used when the component set is initially inserted into a design.
Therefore, place the most useful or commonly used variant in the top-left position.
When a component set contains many variants, organize them into rows, columns, or grids so that the structure is easy to understand.
Small Medium Large
Primary Default Default Default
Primary Hover Hover Hover
Primary Pressed Pressed Pressed
Primary Disabled Disabled Disabled
Secondary Default Default Default
Secondary Hover Hover Hover
Secondary Disabled Disabled Disabled
Every variant in a component set should have a unique combination of property values. Two variants cannot have the exact same property-value combination, even if they look visually different.
Type = Primary
Size = Large
State = Default
If another variant uses the same combination, Figma will report a conflicting value combination.
Variant explosion occurs when the number of variants grows rapidly because too many properties are combined.
3 Types × 3 Sizes × 4 States × 2 Themes
= 72 theoretical combinations
You do not necessarily need to create all 72 combinations. Create only the combinations that are actually required by the design system.
Instead of using one property for multiple unrelated concepts, create separate properties.
Less flexible:
Style:
Primary Large
Primary Small
Secondary Large
Secondary Small
Better:
Type:
Primary
Secondary
Size:
Small
Large
Separate properties make the system easier to understand and provide more flexibility.
| Requirement | Recommended Approach |
|---|---|
| Different visual state | Variant |
| Different component size | Variant |
| Show or hide an icon | Boolean property |
| Show or hide a badge | Boolean property |
If the only difference is text content, creating a separate variant for every text string is usually unnecessary. A Text property is more appropriate for editable content.
Variant:
State = Default
Text Property:
Label = Save
Label = Continue
Label = Submit
Variants represent predefined versions of a component. Instance Swap properties are useful when a nested component needs to be replaced by another component.
Variant:
State = Hover
Instance Swap:
Icon = Search
Icon = Download
Icon = Arrow Right
Variants are mainly used to manage different states or types of a component. Slots are designed for flexible content areas where designers need to add, edit, or rearrange content while maintaining the component's underlying design-system structure.
| Feature | Best Use |
|---|---|
| Variant | States, sizes, types, predictable variations |
| Boolean | Show or hide layers |
| Text | Change text content |
| Instance Swap | Replace nested components |
| Slot | Flexible content areas |
Auto Layout and variants work well together. Auto Layout can control spacing, alignment, padding, and resizing within each variant.
Variants can represent meaningful size or layout configurations when the component genuinely requires distinct designs.
Card
├── Compact
├── Standard
└── Large
However, do not create variants simply because a component needs to resize automatically. Auto Layout and responsive sizing may be a better solution.
Variants can be used to create interactive components. Figma's interactive components allow prototype interactions between variants in the same component set.
Checkbox
├── Checked = False
└── Checked = True
Prototype:
Click → Change to Checked
Button Component Set
State = Default
State = Hover
State = Pressed
State = Disabled
Interaction:
Hover → Change to Hover
Press → Change to Pressed
Checkbox
Variant 1:
State = Unchecked
Variant 2:
State = Checked
Prototype:
On Click
↓
Change to
↓
Checked
Variants are particularly valuable in design systems because they turn scattered component versions into an organized and navigable system.
Well-named variant properties can communicate design intent to developers.
Button
Type = Primary
Size = Large
State = Disabled
This structure can map naturally to component props in a front-end system.
Figma:
Button
Type = Primary
Size = Large
State = Disabled
Possible code concept:
<Button
type="primary"
size="large"
state="disabled"
/>
Consistent naming between Figma and code can make developer handoff easier and reduce ambiguity.
Complex component sets should include documentation that explains their purpose, available properties, values, states, and usage rules.
Button
Type:
Primary - Main action
Secondary - Supporting action
Destructive - Dangerous action
Size:
Small - Compact interfaces
Medium - Default usage
Large - Prominent actions
State:
Default - Normal state
Hover - Pointer interaction
Pressed - Active interaction
Disabled - Unavailable action
Figma allows component sets and individual variants to have descriptions. Descriptions can help designers and developers understand the intended use of a component and its variations.
Use descriptions for important usage rules, accessibility guidance, content requirements, or unusual component behavior.
Component sets can be published to Figma libraries on supported paid plans. When published, collaborators can access the component set from the Assets panel and configure its available variant properties.
Before publishing, verify naming, property structure, visual consistency, documentation, accessibility, and variant combinations.
A well-structured variant system improves collaboration between designers and developers.
One of the most common mistakes is creating a variant for every small customization.
Before creating a variant, ask:
Creating too many variant properties can make a component difficult to understand. Use only the properties that represent real design-system dimensions.
Names such as Property 1, Property 2, and Property 3 do not communicate design intent.
Use meaningful names such as:
Type
Size
State
Theme
Density
Do not mix different naming styles for similar values.
Poor:
Small
medium
LARGE
Big
Better:
Small
Medium
Large
Every variant should have a unique combination of property values. If two variants have the same values, review whether one of the properties is missing or whether the variants should actually be separate.
Test variants with realistic content.
Short:
Save
Medium:
Save Changes
Long:
Save Changes and Continue
This is especially important for buttons, cards, navigation items, and form controls.
States such as Focus, Disabled, Error, Selected, and Active should be visually understandable and should meet appropriate accessibility requirements. Do not rely only on subtle color changes to communicate important interaction states.
Before sharing a component set with a team, test every important property and combination.
Create a complete Button component set.
Button
Type:
Primary
Secondary
Destructive
Size:
Small
Medium
Large
State:
Default
Hover
Pressed
Disabled
Use Auto Layout and consistent spacing across all variants.
Create an Input component set with different states and sizes.
Input
Size:
Small
Medium
Large
State:
Default
Focus
Filled
Error
Success
Disabled
Test the component with realistic placeholder and input text.
Navigation Item
State:
Default
Hover
Active
Disabled
Notification:
On
Off
Consider using a Boolean property for Notification if it only controls whether a notification element is shown or hidden.
Card
Type:
Standard
Featured
Size:
Compact
Standard
Large
State:
Default
Hover
Disabled
Create a Toggle component using two main variants.
Toggle
├── State = Off
└── State = On
Connect the two variants with a Change to interaction to create an interactive prototype.
Badge
Type:
Success
Warning
Error
Information
Neutral
Size:
Small
Medium
Large
Understand Component Requirements
↓
Identify Meaningful Variations
↓
Create Base Component
↓
Create Related Components
↓
Combine as Variants
↓
Define Variant Properties
↓
Define Variant Values
↓
Rename Properties
↓
Organize Component Set
↓
Set Default Variant
↓
Add Other Component Properties
↓
Apply Auto Layout
↓
Create Interactions
↓
Test Variants
↓
Document Component
↓
Publish to Library When Appropriate
↓
Use in Product Designs
A scalable component architecture separates meaningful design dimensions rather than combining unrelated changes into one property.
Button
├── Type
│ ├── Primary
│ ├── Secondary
│ └── Destructive
├── Size
│ ├── Small
│ ├── Medium
│ └── Large
├── State
│ ├── Default
│ ├── Hover
│ ├── Pressed
│ └── Disabled
└── Content
├── Label
└── Optional Icon
Variants and other component properties can be used together to create flexible but controlled components.
Button
Variant:
Type = Primary
Size = Large
State = Default
Boolean:
Show Icon = True
Text:
Label = Continue
Instance Swap:
Icon = Arrow Right
Variables and component variants solve different but complementary design-system problems. Variants can represent component states or structural variations, while variables can help manage reusable design values such as colors, spacing, dimensions, and typography-related tokens.
Using both appropriately can reduce duplication and make a design system easier to scale.
A good variant architecture makes components easier to maintain because related versions are grouped together. When the base component structure changes, designers can manage the corresponding variants as one component family instead of searching through unrelated standalone components.
Variants encourage designers to use predefined component states and styles rather than recreating them manually. This helps reduce inconsistencies in spacing, typography, colors, borders, radii, and interaction states.
Clear variant names make it easier for developers to understand which component state or configuration is intended.
Button
Type = Destructive
Size = Medium
State = Disabled
This can communicate the intended design state much more clearly than an unnamed or manually modified component.
| Requirement | Recommended Feature |
|---|---|
| Different component state | Variant |
| Different component size | Variant |
| Different component type | Variant |
| Show or hide an element | Boolean property |
| Change text | Text property |
| Replace nested component | Instance Swap |
| Flexible content region | Slot |
| Automatic spacing and resizing | Auto Layout |
| Reusable design values | Variables |
Component Variants are different versions of related components grouped into a single component set.
A component set is a container that groups related component variants.
A variant property defines an attribute by which variants differ, such as Size, Type, or State.
A variant value is a specific option within a variant property, such as Small, Medium, Large, Default, or Disabled.
They organize related components, reduce library clutter, and make predefined component variations easier to select and maintain.
A component is a reusable design object, while a variant is a specific version of a component within a component set.
Yes. Variants within the same component set can be connected using Change to interactions to create interactive components.
Variant explosion is the rapid growth of variants caused by combining too many properties and values.
Use only meaningful combinations and use Boolean, Text, Instance Swap, Slot, Auto Layout, Variables, or other appropriate features when they better match the requirement.
Descriptive names make the component easier to understand, configure, document, and use in a design system.
Create a complete Button component set in Figma.
| Term | Meaning |
|---|---|
| Component | Reusable design object |
| Variant | Specific version of a component |
| Component Set | Container holding related variants |
| Variant Property | Defines a dimension of variation |
| Variant Value | Specific option of a variant property |
| Instance | Reusable copy of a component or component set |
| Boolean Property | Controls visibility |
| Text Property | Controls editable text |
| Instance Swap | Controls replaceable nested components |
| Slot | Provides flexible content areas |
| Auto Layout | Controls layout, spacing, and resizing |
| Variable | Stores reusable design values |
Understand Requirements
↓
Identify Meaningful Variations
↓
Create Base Component
↓
Create Related Components
↓
Combine as Variants
↓
Create Variant Properties
↓
Define Variant Values
↓
Rename Properties Clearly
↓
Organize Component Set
↓
Choose Default Variant
↓
Add Other Component Properties
↓
Apply Auto Layout
↓
Create Interactive States
↓
Test All Important Combinations
↓
Document Component
↓
Publish to Library When Appropriate
↓
Use Variants in Product Screens
Component Variants are an important Figma feature for building organized, reusable, and scalable design systems. They allow related component versions to be grouped inside a component set and controlled through meaningful variant properties and values. Variants are especially useful for predictable differences such as states, sizes, types, and styles.
A professional component system should not use variants for every possible customization. Instead, combine variants with Boolean, Text, Instance Swap, Slot, Auto Layout, and Variables according to the type of design requirement. With clear naming, unique combinations, proper organization, testing, documentation, and thoughtful property architecture, Component Variants can make a Figma design system significantly easier to use and maintain.
For detailed Figma training and practical design-system learning, visit JustAcademy Figma Training and Register for Figma Course Demo.
